<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <title>
Bugzilla</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" title="style" type="text/css" href="./../../../style.css" media="all" >

</head>
  <body id="pod">
<p class="backlinktop"><b><a name="___top" href="index.html" accesskey="1" title="All Documents">&lt;&lt;</a></b></p>
<h1>Bugzilla</h1>
<div class='indexgroup'>
<ul   class='indexList indexList1'>
  <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
  <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
  <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
  <li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
</ul>
</div>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>

<p>Bugzilla - Semi-persistent collection of various objects used by scripts and modules</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>

<pre  class="code">  use Bugzilla;

  sub someModulesSub {
    Bugzilla-&#62;dbh-&#62;prepare(...);
    Bugzilla-&#62;template-&#62;process(...);
  }</pre>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>

<p>Several Bugzilla &#39;things&#39; are used by a variety of modules and scripts. This includes database handles, template objects, and so on.</p>

<p>This module is a singleton intended as a central place to store these objects. This approach has several advantages:</p>

<ul>
<li>They&#39;re not global variables, so we don&#39;t have issues with them staying around with mod_perl</li>

<li>Everything is in one central place, so it&#39;s easy to access, modify, and maintain</li>

<li>Code in modules can get access to these objects without having to have them all passed from the caller, and the caller&#39;s caller, and....</li>

<li>We can reuse objects across requests using mod_perl where appropriate (eg templates), whilst destroying those which are only valid for a single request (such as the current user)</li>
</ul>

<p>Note that items accessible via this object are demand-loaded when requested.</p>

<p>For something to be added to this object, it should either be able to benefit from persistence when run under mod_perl (such as the a <code  class="code">template</code> object), or should be something which is globally required by a large ammount of code (such as the current <code  class="code">user</code> object).</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>

<p>Note that all <code  class="code">Bugzilla</code> functionality is method based; use <code  class="code">Bugzilla-&#62;dbh</code> rather than <code  class="code">Bugzilla::dbh</code>. Nothing cares about this now, but don&#39;t rely on that.</p>

<dl>
<dt><a name="template"
><code  class="code">template</code></a></dt>

<dd>
<p>The current <code  class="code">Template</code> object, to be used for output</p>

<dt><a name="template_inner"
><code  class="code">template_inner</code></a></dt>

<dd>
<p>If you ever need a <a href="./Bugzilla/Template.html" class="podlinkpod"
>Bugzilla::Template</a> object while you&#39;re already processing a template, use this. Also use it if you want to specify the language to use. If no argument is passed, it uses the last language set. If the argument is &#34;&#34; (empty string), the language is reset to the current one (the one used by Bugzilla-&#62;template).</p>

<dt><a name="cgi"
><code  class="code">cgi</code></a></dt>

<dd>
<p>The current <code  class="code">cgi</code> object. Note that modules should <b>not</b> be using this in general. Not all Bugzilla actions are cgi requests. Its useful as a convenience method for those scripts/templates which are only use via CGI, though.</p>

<dt><a name="input_params"
><code  class="code">input_params</code></a></dt>

<dd>
<p>When running under the WebService, this is a hashref containing the arguments passed to the WebService method that was called. When running in a normal script, this is a hashref containing the contents of the CGI parameters.</p>

<p>Modifying this hashref will modify the CGI parameters or the WebService arguments (depending on what <code  class="code">input_params</code> currently represents).</p>

<p>This should be used instead of <a href="#cgi" class="podlinkpod"
>&#34;cgi&#34;</a> in situations where your code could be being called by either a normal CGI script or a WebService method, such as during a code hook.</p>

<p><b>Note:</b> When <code  class="code">input_params</code> represents the CGI parameters, any parameter specified more than once (like <code  class="code">foo=bar&#38;foo=baz</code>) will appear as an arrayref in the hash, but any value specified only once will appear as a scalar. This means that even if a value <i>can</i> appear multiple times, if it only <i>does</i> appear once, then it will be a scalar in <code  class="code">input_params</code>, not an arrayref.</p>

<dt><a name="user"
><code  class="code">user</code></a></dt>

<dd>
<p><code  class="code">undef</code> if there is no currently logged in user or if the login code has not yet been run. If an sudo session is in progress, the <code  class="code">Bugzilla::User</code> corresponding to the person who is being impersonated. If no session is in progress, the current <code  class="code">Bugzilla::User</code>.</p>

<dt><a name="set_user"
><code  class="code">set_user</code></a></dt>

<dd>
<p>Allows you to directly set what <a href="#user" class="podlinkpod"
>&#34;user&#34;</a> will return. You can use this if you want to bypass <a href="#login" class="podlinkpod"
>&#34;login&#34;</a> for some reason and directly &#34;log in&#34; a specific <a href="./Bugzilla/User.html" class="podlinkpod"
>Bugzilla::User</a>. Be careful with it, though!</p>

<dt><a name="sudoer"
><code  class="code">sudoer</code></a></dt>

<dd>
<p><code  class="code">undef</code> if there is no currently logged in user, the currently logged in user is not in the <i>sudoer</i> group, or there is no session in progress. If an sudo session is in progress, returns the <code  class="code">Bugzilla::User</code> object corresponding to the person who logged in and initiated the session. If no session is in progress, returns the <code  class="code">Bugzilla::User</code> object corresponding to the currently logged in user.</p>

<dt><a 
><code  class="code">sudo_request</code> This begins an sudo session for the current request. It is meant to be used when a session has just started. For normal use, sudo access should normally be set at login time.</a></dt>

<dd>
<dt><a name="login"
><code  class="code">login</code></a></dt>

<dd>
<p>Logs in a user, returning a <code  class="code">Bugzilla::User</code> object, or <code  class="code">undef</code> if there is no logged in user. See <a href="./Bugzilla/Auth.html" class="podlinkpod"
>Bugzilla::Auth</a>, and <a href="./Bugzilla/User.html" class="podlinkpod"
>Bugzilla::User</a>.</p>

<dt><a name="page_requires_login"
><code  class="code">page_requires_login</code></a></dt>

<dd>
<p>If the current page always requires the user to log in (for example, <code  class="code">enter_bug.cgi</code> or any page called with <code  class="code">?GoAheadAndLogIn=1</code>) then this will return something true. Otherwise it will return false. (This is set when you call <a href="#login" class="podlinkpod"
>&#34;login&#34;</a>.)</p>

<dt><a name="logout($option)"
><code  class="code">logout($option)</code></a></dt>

<dd>
<p>Logs out the current user, which involves invalidating user sessions and cookies. Three options are available from <a href="./Bugzilla/Constants.html" class="podlinkpod"
>Bugzilla::Constants</a>: LOGOUT_CURRENT (the default), LOGOUT_ALL or LOGOUT_KEEP_CURRENT.</p>

<dt><a name="logout_user($user)"
><code  class="code">logout_user($user)</code></a></dt>

<dd>
<p>Logs out the specified user (invalidating all his sessions), taking a Bugzilla::User instance.</p>

<dt><a name="logout_by_id($id)"
><code  class="code">logout_by_id($id)</code></a></dt>

<dd>
<p>Logs out the user with the id specified. This is a compatibility function to be used in callsites where there is only a userid and no Bugzilla::User instance.</p>

<dt><a name="logout_request"
><code  class="code">logout_request</code></a></dt>

<dd>
<p>Essentially, causes calls to <code  class="code">Bugzilla-&#62;user</code> to return <code  class="code">undef</code>. This has the effect of logging out a user for the current request only; cookies and database sessions are left intact.</p>

<dt><a name="error_mode"
><code  class="code">error_mode</code></a></dt>

<dd>
<p>Call either <code  class="code">Bugzilla-</code>error_mode(Bugzilla::Constants::ERROR_MODE_DIE)&#62; or <code  class="code">Bugzilla-</code>error_mode(Bugzilla::Constants::ERROR_MODE_DIE_SOAP_FAULT)&#62; to change this flag&#39;s default of <code  class="code">Bugzilla::Constants::ERROR_MODE_WEBPAGE</code> and to indicate that errors should be passed to error mode specific error handlers rather than being sent to a browser and finished with an exit().</p>

<p>This is useful, for example, to keep <code  class="code">eval</code> blocks from producing wild HTML on errors, making it easier for you to catch them. (Remember to reset the error mode to its previous value afterwards, though.)</p>

<p><code  class="code">Bugzilla-</code>error_mode&#62; will return the current state of this flag.</p>

<p>Note that <code  class="code">Bugzilla-</code>error_mode&#62; is being called by <code  class="code">Bugzilla-</code>usage_mode&#62; on usage mode changes.</p>

<dt><a name="usage_mode"
><code  class="code">usage_mode</code></a></dt>

<dd>
<p>Call either <code  class="code">Bugzilla-</code>usage_mode(Bugzilla::Constants::USAGE_MODE_CMDLINE)&#62; or <code  class="code">Bugzilla-</code>usage_mode(Bugzilla::Constants::USAGE_MODE_XMLRPC)&#62; near the beginning of your script to change this flag&#39;s default of <code  class="code">Bugzilla::Constants::USAGE_MODE_BROWSER</code> and to indicate that Bugzilla is being called in a non-interactive manner.</p>

<p>This influences error handling because on usage mode changes, <code  class="code">usage_mode</code> calls <code  class="code">Bugzilla-</code>error_mode&#62; to set an error mode which makes sense for the usage mode.</p>

<p><code  class="code">Bugzilla-</code>usage_mode&#62; will return the current state of this flag.</p>

<dt><a name="installation_mode"
><code  class="code">installation_mode</code></a></dt>

<dd>
<p>Determines whether or not installation should be silent. See <a href="./Bugzilla/Constants.html" class="podlinkpod"
>Bugzilla::Constants</a> for the <code  class="code">INSTALLATION_MODE</code> constants.</p>

<dt><a name="installation_answers"
><code  class="code">installation_answers</code></a></dt>

<dd>
<p>Returns a hashref representing any &#34;answers&#34; file passed to <em  class="code">checksetup.pl</em>, used to automatically answer or skip prompts.</p>

<dt><a name="dbh"
><code  class="code">dbh</code></a></dt>

<dd>
<p>The current database handle. See <a href="./DBI.html" class="podlinkpod"
>DBI</a>.</p>

<dt><a name="dbh_main"
><code  class="code">dbh_main</code></a></dt>

<dd>
<p>The main database handle. See <a href="./DBI.html" class="podlinkpod"
>DBI</a>.</p>

<dt><a name="languages"
><code  class="code">languages</code></a></dt>

<dd>
<p>Currently installed languages. Returns a reference to a list of RFC 1766 language tags of installed languages.</p>

<dt><a name="switch_to_shadow_db"
><code  class="code">switch_to_shadow_db</code></a></dt>

<dd>
<p>Switch from using the main database to using the shadow database.</p>

<dt><a name="switch_to_main_db"
><code  class="code">switch_to_main_db</code></a></dt>

<dd>
<p>Change the database object to refer to the main database.</p>

<dt><a name="params"
><code  class="code">params</code></a></dt>

<dd>
<p>The current Parameters of Bugzilla, as a hashref. If <code  class="code">data/params</code> does not exist, then we return an empty hashref. If <code  class="code">data/params</code> is unreadable or is not valid perl, we <code  class="code">die</code>.</p>

<dt><a name="local_timezone"
><code  class="code">local_timezone</code></a></dt>

<dd>
<p>Returns the local timezone of the Bugzilla installation, as a DateTime::TimeZone object. This detection is very time consuming, so we cache this information for future references.</p>

<dt><a name="job_queue"
><code  class="code">job_queue</code></a></dt>

<dd>
<p>Returns a <a href="./Bugzilla/JobQueue.html" class="podlinkpod"
>Bugzilla::JobQueue</a> that you can use for queueing jobs. Will throw an error if job queueing is not correctly configured on this Bugzilla installation.</p>

<dt><a name="feature"
><code  class="code">feature</code></a></dt>

<dd>
<p>Tells you whether or not a specific feature is enabled. For names of features, see <code  class="code">OPTIONAL_MODULES</code> in <code  class="code">Bugzilla::Install::Requirements</code>.</p>
</dd>
</dl>
<p class="backlinkbottom"><b><a name="___bottom" href="index.html" title="All Documents">&lt;&lt;</a></b></p>

<!-- end doc -->

</body></html>
